home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / SetResult.3 < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_SetResult(3)     Tcl Library Procedures                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_SetResult,     Tcl_AppendResult,      Tcl_AppendElement,
  12.      Tcl_ResetResult - manipulate Tcl result string
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      Tcl_SetResult(_i_n_t_e_r_p, _s_t_r_i_n_g, _f_r_e_e_P_r_o_c)
  18.  
  19.      Tcl_AppendResult(_i_n_t_e_r_p, _s_t_r_i_n_g, _s_t_r_i_n_g, ... , (char *) NULL)
  20.  
  21.      Tcl_AppendElement(_i_n_t_e_r_p, _s_t_r_i_n_g)                             |
  22.  
  23.      Tcl_ResetResult(_i_n_t_e_r_p)
  24.  
  25.      Tcl_FreeResult(_i_n_t_e_r_p)
  26.  
  27. ARGUMENTS
  28.      Tcl_Interp     *_i_n_t_e_r_p    (out)     Interpreter whose result
  29.                                          is to be modified.
  30.  
  31.      char           *_s_t_r_i_n_g    (in)      String value  to  become
  32.                                          result  for _i_n_t_e_r_p or to
  33.                                          be appended to  existing
  34.                                          result.
  35.  
  36.      Tcl_FreeProc   _f_r_e_e_P_r_o_c   (in)      Address of procedure  to
  37.                                          call  to release storage
  38.                                          at      _s_t_r_i_n_g,       or
  39.                                          TCL_STATIC, TCL_DYNAMIC,
  40.                                          or TCL_VOLATILE.
  41. _________________________________________________________________
  42.  
  43.  
  44. DESCRIPTION
  45.      The procedures described here are utilities for setting  the
  46.      result/error string in a Tcl interpreter.
  47.  
  48.      Tcl_SetResult arranges for _s_t_r_i_n_g to be  the  return  string
  49.      for  the current Tcl command in _i_n_t_e_r_p, replacing any exist-
  50.      ing result.  If _f_r_e_e_P_r_o_c is TCL_STATIC it means that  _s_t_r_i_n_g
  51.      refers  to  an area of static storage that is guaranteed not
  52.      to be modified until at least the next call to Tcl_Eval.  If
  53.      _f_r_e_e_P_r_o_c  is  TCL_DYNAMIC it means that _s_t_r_i_n_g was allocated
  54.      with a call to malloc() and is now the property of  the  Tcl
  55.      system.  Tcl_SetResult will arrange for the string's storage
  56.      to be released by  calling  free()  when  it  is  no  longer
  57.      needed.   If  _f_r_e_e_P_r_o_c  is TCL_VOLATILE it means that _s_t_r_i_n_g
  58.      points to an area of memory that is likely to be overwritten
  59.      when Tcl_SetResult returns (e.g. it points to something in a
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_SetResult(3)     Tcl Library Procedures                   7.0
  71.  
  72.  
  73.  
  74.      stack frame).  In this case Tcl_SetResult will make  a  copy
  75.      of  the  string in dynamically allocated storage and arrange
  76.      for the copy to be the return string  for  the  current  Tcl
  77.      command.
  78.  
  79.      If _f_r_e_e_P_r_o_c isn't one of the values TCL_STATIC, TCL_DYNAMIC,
  80.      and TCL_VOLATILE, then it is the address of a procedure that
  81.      Tcl should call to free the string.   This  allows  applica-
  82.      tions  to  use non-standard storage allocators.  When Tcl no
  83.      longer needs the  storage  for  the  string,  it  will  call
  84.      _f_r_e_e_P_r_o_c.   _F_r_e_e_P_r_o_c  should  have arguments and result that
  85.      match the type Tcl_FreeProc:
  86.  
  87.           typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);
  88.  
  89.      When _f_r_e_e_P_r_o_c is called, its _b_l_o_c_k_P_t_r will  be  set  to  the
  90.      value of _s_t_r_i_n_g passed to Tcl_SetResult.
  91.  
  92.      If  _s_t_r_i_n_g  is  NULL,   then   _f_r_e_e_P_r_o_c   is   ignored   and
  93.      Tcl_SetResult re-initializes _i_n_t_e_r_p's result to point to the
  94.      pre-allocated result area,  with  an  empty  string  in  the
  95.      result area.
  96.  
  97.      If Tcl_SetResult is called at a time  when  _i_n_t_e_r_p  holds  a
  98.      result,  Tcl_SetResult does whatever is necessary to dispose
  99.      of the old result  (see  the  Tcl_Interp  manual  entry  for
  100.      details on this).
  101.  
  102.      Tcl_AppendResult makes it easy to build up  Tcl  results  in
  103.      pieces.   It  takes each of its _s_t_r_i_n_g arguments and appends
  104.      them in order to the current result associated with  _i_n_t_e_r_p.
  105.      If the result is in its initialized empty state (e.g. a com-
  106.      mand procedure was just invoked or Tcl_ResetResult was  just
  107.      called),  then  Tcl_AppendResult sets the result to the con-
  108.      catenation of its _s_t_r_i_n_g arguments.  Tcl_AppendResult may be
  109.      called  repeatedly  as  additional  pieces of the result are
  110.      produced.  Tcl_AppendResult takes care of  all  the  storage
  111.      management  issues associated with managing _i_n_t_e_r_p's result,
  112.      such as allocating a larger result area if  necessary.   Any
  113.      number  of  _s_t_r_i_n_g arguments may be passed in a single call;
  114.      the last argument in the list must be a NULL pointer.
  115.  
  116.      Tcl_AppendElement is similar to Tcl_AppendResult in that  it
  117.      allows   results   to  be  built  up  in  pieces.   However,
  118.      Tcl_AppendElement takes only a single _s_t_r_i_n_g argument and it
  119.      appends  that argument to the current result as a proper Tcl
  120.      list element.  Tcl_AppendElement adds backslashes or  braces
  121.      if necessary to ensure that _i_n_t_e_r_p's result can be parsed as
  122.      a list and that _s_t_r_i_n_g will be extracted as  a  single  ele-
  123.      ment.  Under normal conditions, Tcl_AppendElement will add a
  124.      space character to _i_n_t_e_r_p's result just  before  adding  the
  125.      new  list  element,  so that the list elements in the result
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_SetResult(3)     Tcl Library Procedures                   7.0
  137.  
  138.  
  139.  
  140.      are properly separated.  However if the new list element  is  |
  141.      the  first  in  a  list  or  sub-list (i.e. _i_n_t_e_r_p's current  |
  142.      result is empty, or consists of the single character  ``{'',  |
  143.      or ends in the characters `` {'') then no space is added.
  144.  
  145.      Tcl_ResetResult clears the result for  _i_n_t_e_r_p,  freeing  the
  146.      memory  associated with it if the current result was dynami-
  147.      cally allocated.  It leaves the result in  its  normal  ini-
  148.      tialized  state  with  _i_n_t_e_r_p->_r_e_s_u_l_t  pointing  to a static
  149.      buffer containing TCL_RESULT_SIZE characters, of  which  the
  150.      first  character  is  zero.  Tcl_ResetResult also clears the
  151.      error    state    managed    by     Tcl_AddErrorInfo     and
  152.      Tcl_SetErrorCode.
  153.  
  154.      Tcl_FreeResult is a macro that performs part of the work  of
  155.      Tcl_ResetResult.   It  frees  up  the memory associated with
  156.      _i_n_t_e_r_p's result and sets _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to  zero,  but  it
  157.      doesn't   change   _i_n_t_e_r_p->_r_e_s_u_l_t   or  clear  error  state.
  158.      Tcl_FreeResult is most commonly used  when  a  procedure  is
  159.      about to replace one result value with another.
  160.  
  161.  
  162. SEE ALSO
  163.      Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
  164.  
  165.  
  166. KEYWORDS
  167.      append, command, element, list, result, return value, inter-
  168.      preter
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.